.\" $Id: PAPI_get_hardware_info.3,v 1.10 2004/11/29 20:44:16 mucci Exp $
.TH PAPI_get_hardware_info 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_get_hardware_info \- get information about the system hardware

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "const PAPI_hw_info_t *PAPI_get_hardware_info(void);"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_get_hardware_info(C_INT\  ncpu,\  C_INT\  nnodes,\ \
           C_INT\  totalcpus,\  C_INT\  vendor,\ \
           C_STRING\  vendor_string, \  C_INT\  model,\ \
           C_STRING\  model_string,\
           C_FLOAT\  revision,\  C_FLOAT\  mhz)
.fi

.SH DESCRIPTION
In C, this function returns a pointer to a structure containing information
about the hardware on which the program runs. In Fortran, the values 
of the structure are returned explicitly.

.SH NOTE
The C structure contains detailed information about cache and TLB sizes. 
This information is not available from Fortran.

.SH ARGUMENTS
The following arguments are implicit in the structure returned by the C function,
or explicitly returned by Fortran.
.LP
.I ncpu
--  number of CPUs in an SMP Node
.LP
.I nnodes
--  number of Nodes in the entire system
.LP
.I totalcpus
--  total number of CPUs in the entire system
.LP
.I vendor
--  vendor id number of CPU
.LP
.I vendor_string
--  vendor id string of CPU
.LP
.I model
--  model number of CPU
.LP
.I model_string
--  model string of CPU
.LP
.I revision
--  Revision number of CPU
.LP
.I mhz
--  Cycle time of this CPU; *may* be an estimate
generated at init time with a quick timing routine
.LP
.I mem_hierarchy
-- PAPI memory heirarchy description

.SH RETURN VALUES
On success, the C function returns a non-NULL pointer, 
and the Fortran function returns 
.B PAPI_OK.
 On error, NULL is returned by the C function, 
and a non-zero error code is returned by the Fortran function.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.

.SH EXAMPLE
.LP
.nf
.if t .ft CW
const PAPI_hw_info_t *hwinfo = NULL;
	
if (PAPI_library_init(PAPI_VER_CURRENT) != PAPI_VER_CURRENT)
  exit(1);

if ((hwinfo = PAPI_get_hardware_info()) == NULL)
  exit(1);

printf("%d CPU's at %f Mhz.\en",hwinfo->totalcpus,hwinfo->mhz);
.if t .ft P
.fi

.SH DATA STRUCTURE
The C data structure returned by this function is found in 
.B papi.h and reproduced below:
.LP
.nf
.if t .ft CW
   typedef struct _papi_mh_tlb_info {
      int type; /* See papi.h for PAPI_MH definitions. */
      int num_entries;
      int associativity;
   } PAPI_mh_tlb_info_t;

   typedef struct _papi_mh_cache_info {
      int type; /* See papi.h for PAPI_MH definitions. */
      int size;
      int line_size;
      int num_lines;
      int associativity;
   } PAPI_mh_cache_info_t;

   typedef struct _papi_mh_level_info {
      PAPI_mh_tlb_info_t   tlb[2];
      PAPI_mh_cache_info_t cache[2];
   } PAPI_mh_level_t;

   typedef struct _papi_mh_info { /* mh for mem hierarchy maybe? */
      int levels;
      PAPI_mh_level_t level[PAPI_MAX_MEM_HIERARCHY_LEVELS];
   } PAPI_mh_info_t;

   typedef struct _papi_hw_info {
      int ncpu;                     /* Number of CPU's in an SMP Node */
      int nnodes;                   /* Number of Nodes in the entire system */
      int totalcpus;                /* Total number of CPU's in the entire system */
      int vendor;                   /* Vendor number of CPU */
      char vendor_string[PAPI_MAX_STR_LEN];     /* Vendor string of CPU */
      int model;                    /* Model number of CPU */
      char model_string[PAPI_MAX_STR_LEN];      /* Model string of CPU */
      float revision;               /* Revision of CPU */
      float mhz;                    /* Cycle time of this CPU, *may* be estimated at 
                                       init time with a quick timing routine */
     PAPI_mh_info_t mem_hierarchy;  /* PAPI memory heirarchy description */
   } PAPI_hw_info_t;

.if t .ft P
.fi

.SH BUGS
If called before 
.B PAPI_library_init()
the behavior of the routine is undefined.

.SH SEE ALSO
.BR PAPI_library_init "(3), "
.BR PAPI_get_dmem_info "(3), "
.BR PAPI_get_opt "(3), "
.BR PAPI_get_executable_info "(3)"
